﻿/*	
	stencil - action script 3 isometric game engine.

	http://code.google.com/p/stencilas3/
	
	Copyright (c) 2010 Max Zhuravkov, All Rights Reserved.

	Permission is hereby granted, free of charge, to any person obtaining a copy of
	this software and associated documentation files (the "Software"), to deal in
	the Software without restriction, including without limitation the rights to
	use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
	of the Software, and to permit persons to whom the Software is furnished to do
	so, subject to the following conditions:

	The above copyright notice and this permission notice shall be included in all
	copies or substantial portions of the Software.

	THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
	IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
	FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
	AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
	LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
	OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
	SOFTWARE.
*/
package stencil.core.engine.display {
	
	import flash.display.DisplayObject;
	import flash.events.IEventDispatcher;
	import flash.geom.Rectangle;
	import stencil.core.engine.IDisposable;
	import stencil.core.engine.ICameraDisplay;
	import stencil.core.engine.IGrid;
	import stencil.core.engine.ISceneObject;
	
	[Event(name="stnChildAdded",type="stencil.core.engine.display.events.DisplayListEvent")]
		
	[Event(name="stnChildRemoved", type = "stencil.core.engine.display.events.DisplayListEvent")] 
	
	/**
	 * Defines operations for managing display list content such as adding, removing, updating and sorting.
	 */
	public interface IDisplayList extends IEventDispatcher, ICameraDisplay, IGraphicObject {
		
		
		/**
		 * The grid used to calculate object coordinates.
		 */
		function set grid(value:IGrid):void;
		
		function get grid():IGrid;
		
		/**
		 * The flag indicates whether this display list calculates positions of background objects or not. 
		 */
		function get calculateTilePositions():Boolean;
		
		/**
		 * The array of objects that this display list contains.
		 */
		function get children():Array;
		
		/**
		 * The array of tiles that this display list contains.
		 */
		function get tiles():Array;
		
		/**
		 * The depth sort algorithm used by this display list.
		 */
		function set depthSortingAlgorithm(value:IDepthSorting):void;
		
		function get depthSortingAlgorithm():IDepthSorting;
		
		/**
		 * Adds an object to this display list.
		 * 
		 * @param	child	the instance of IDisplayObject to added to this display list.
		 */
		function add(child:IDisplayObject):void;
		
		/**
		 * Removes an object from this display list.
		 * 
		 * @param	child	this instance of IDisplayObject to be removed from this display list.  
		 */
		function remove(child:IDisplayObject):void;
		
		/**
		 * Determines whether the given instance of IDisplayObject is a child of this display list or not.
		 * 
		 * @param	child	the instance of IDisplayObject to test.
		 * @return	true if the given instance is a child of this display list and false otherwise.
		 */
		function contains(child:IDisplayObject):Boolean;
		
		/**
		 * Marks the given instance of IDisplayObject as to be updated during next render call.
		 * 
		 * @param	child	the instance of IDisplayObject to be updated.
		 */
		function update(child:IDisplayObject):void;
		
		/**
		 * Returns child object with the given identifier if any.
		 * 
		 * @param	id	the identifier
		 * 
		 * @return
		 */
		function find(id:String):IDisplayObject;
		
	
		function invalidate():void;
		
		/**
		 * Removes all children from this display list.
		 */
		function clear():void;
		
		/**
		 * Ensures that this display list will be sorted during a later screen update.
		 */
		function sort():void;
	}
	
}